From: Florian Müllner Date: Wed, 23 May 2018 15:55:43 +0000 (+0200) Subject: docs: Use Markdown X-Git-Tag: archive/raspbian/50.5-1+rpi1~1^2~929^2~5^2~56 X-Git-Url: https://dgit.raspbian.org/%22http://www.example.com/cgi/%22/%22http:/www.example.com/cgi/%22?a=commitdiff_plain;h=02bbf409eadd55cf025646567fc898d60c90c0d3;p=gnome-shell.git docs: Use Markdown Markdown produces nicer output where supported, so use that instead of plain ASCII formatting. --- diff --git a/HACKING b/HACKING deleted file mode 100644 index 575be5b7a..000000000 --- a/HACKING +++ /dev/null @@ -1,333 +0,0 @@ -Coding guide -============ - -Our goal is to have all JavaScript code in GNOME follow a consistent style. In -a dynamic language like JavaScript, it is essential to be rigorous about style -(and unit tests), or you rapidly end up with a spaghetti-code mess. - -A quick note ------------- - -Life isn't fun if you can't break the rules. If a rule seems unnecessarily -restrictive while you're coding, ignore it, and let the patch reviewer decide -what to do. - -Indentation and whitespace --------------------------- - -Use four-space indents. Braces are on the same line as their associated -statements. You should only omit braces if *both* sides of the statement are -on one line. - -* One space after the `function` keyword. No space between the function name -* in a declaration or a call. One space before the parens in the `if` -* statements, or `while`, or `for` loops. - - function foo(a, b) { - let bar; - - if (a > b) - bar = do_thing(a); - else - bar = do_thing(b); - - if (var == 5) { - for (let i = 0; i < 10; i++) { - print(i); - } - } else { - print(20); - } - } - -Semicolons ----------- - -JavaScript allows omitting semicolons at the end of lines, but don't. Always -end statements with a semicolon. - -js2-mode --------- - -If using Emacs, do not use js2-mode. It is outdated and hasn't worked for a -while. emacs now has a built-in JavaScript mode, js-mode, based on -espresso-mode. It is the de facto emacs mode for JavaScript. - -File naming and creation ------------------------- - -For JavaScript files, use lowerCamelCase-style names, with a `.js` extension. - -We only use C where gjs/gobject-introspection is not available for the task, or -where C would be cleaner. To work around limitations in -gjs/gobject-introspection itself, add a new method in `shell-util.[ch]`. - -Like many other GNOME projects, we prefix our C source filenames with the -library name followed by a dash, e.g. `shell-app-system.c`. Create a -`-private.h` header when you want to share code internally in the -library. These headers are not installed, distributed or introspected. - -Imports -------- - -Use UpperCamelCase when importing modules to distinguish them from ordinary -variables, e.g. - - const GLib = imports.gi.GLib; - -Imports should be categorized into one of two places. The top-most import block -should contain only "environment imports". These are either modules from -gobject-introspection or modules added by gjs itself. - -The second block of imports should contain only "application imports". These -are the JS code that is in the gnome-shell codebase, -e.g. `imports.ui.popupMenu`. - -Each import block should be sorted alphabetically. Don't import modules you -don't use. - - const GLib = imports.gi.GLib; - const Gio = imports.gi.Gio; - const Lang = imports.lang; - const St = imports.gi.St; - - const Main = imports.ui.main; - const Params = imports.misc.params; - const Tweener = imports.ui.tweener; - const Util = imports.misc.util; - -The alphabetical ordering should be done independently of the location of the -location. Never reference `imports` in actual code. - -Constants ---------- - -We use CONSTANTS_CASE to define constants. All constants should be directly -under the imports: - - const MY_DBUS_INTERFACE = 'org.my.Interface'; - -Variable declaration --------------------- - -Always use either `const` or `let` when defining a variable. - - // Iterating over an array - for (let i = 0; i < arr.length; ++i) { - let item = arr[i]; - } - - // Iterating over an object's properties - for (let prop in someobj) { - ... - } - -If you use "var" then the variable is added to function scope, not block scope. -See [What's new in JavaScript 1.7](https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.7#Block_scope_with_let_%28Merge_into_let_Statement%29) - -Classes -------- - -There are many approaches to classes in JavaScript. We use our own class framework -(sigh), which is built in gjs. The advantage is that it supports inheriting from -GObjects, although this feature isn't used very often in the Shell itself. - - var IconLabelMenuItem = new Lang.Class({ - Name: 'IconLabelMenuItem', - Extends: PopupMenu.PopupMenuBaseItem, - - _init(icon, label) { - this.parent({ reactive: false }); - this.actor.add_child(icon); - this.actor.add_child(label); - }, - - open() { - log("menu opened!"); - } - }); - -* 'Name' is required. 'Extends' is optional. If you leave it out, you will - automatically inherit from Object. - -* Leave a blank line between the "class header" (Name, Extends, and other - things) and the "class body" (methods). Leave a blank line between each - method. - -* No space before the colon, one space after. - -* No trailing comma after the last item. - -* Make sure to use a semicolon after the closing paren to the class. It's - still a giant function call, even though it may resemble a more - conventional syntax. - -GObject Introspection ---------------------- - -GObject Introspection is a powerful feature that allows us to have native -bindings for almost any library built around GObject. If a library requires -you to inherit from a type to use it, you can do so: - - var MyClutterActor = new Lang.Class({ - Name: 'MyClutterActor', - Extends: Clutter.Actor, - - vfunc_get_preferred_width(actor, forHeight) { - return [100, 100]; - }, - - vfunc_get_preferred_height(actor, forWidth) { - return [100, 100]; - }, - - vfunc_paint(actor) { - let alloc = this.get_allocation_box(); - Cogl.set_source_color4ub(255, 0, 0, 255); - Cogl.rectangle(alloc.x1, alloc.y1, - alloc.x2, alloc.y2); - } - }); - -Translatable strings, `environment.js` --------------------------------------- - -We use gettext to translate the GNOME Shell into all the languages that GNOME -supports. The `gettext` function is aliased globally as `_`, you do not need to -explicitly import it. This is done through some magic in the -[environment.js](http://git.gnome.org/browse/gnome-shell/tree/js/ui/environment.js) -file. If you can't find a method that's used, it's probably either in gjs itself -or installed on the global object from the Environment. - -Use 'single quotes' for programming strings that should not be translated -and "double quotes" for strings that the user may see. This allows us to -quickly find untranslated or mistranslated strings by grepping through the -sources for double quotes without a gettext call around them. - -`actor` and `_delegate` ------------------------ - -gjs allows us to set so-called "expando properties" on introspected objects, -allowing us to treat them like any other. Because the Shell was built before -you could inherit from GTypes natively in JS, we usually have a wrapper class -that has a property called `actor`. We call this wrapper class the "delegate". - -We sometimes use expando properties to set a property called `_delegate` on -the actor itself: - - var MyClass = new Lang.Class({ - Name: 'MyClass', - - _init() { - this.actor = new St.Button({ text: "This is a button" }); - this.actor._delegate = this; - - this.actor.connect('clicked', this._onClicked.bind(this)); - }, - - _onClicked(actor) { - actor.set_label("You clicked the button!"); - } - }); - -The 'delegate' property is important for anything which trying to get the -delegate object from an associated actor. For instance, the drag and drop -system calls the `handleDragOver` function on the delegate of a "drop target" -when the user drags an item over it. If you do not set the `_delegate` -property, your actor will not be able to be dropped onto. - -Functional style ----------------- - -JavaScript Array objects offer a lot of common functional programming -capabilities such as forEach, map, filter and so on. You can use these when -they make sense, but please don't have a spaghetti mess of function programming -messed in a procedural style. Use your best judgment. - -Closures --------- - -`this` will not be captured in a closure, it is relative to how the closure is -invoked, not to the value of this where the closure is created, because "this" -is a keyword with a value passed in at function invocation time, it is not a -variable that can be captured in closures. - -All closures should be wrapped with Function.prototype.bind or use arrow -notation. - - const Lang = imports.lang; - - let closure1 = () => { this._fnorbate(); }; - let closure2 = this._fnorbate.bind(this); - -A more realistic example would be connecting to a signal on a method of a -prototype: - - const Lang = imports.lang; - const FnorbLib = imports.fborbLib; - - var MyClass = new Lang.Class({ - _init() { - let fnorb = new FnorbLib.Fnorb(); - fnorb.connect('frobate', this._onFnorbFrobate.bind(this)); - }, - - _onFnorbFrobate(fnorb) { - this._updateFnorb(); - } - }); - -Object literal syntax ---------------------- - -In JavaScript, these are equivalent: - - foo = { 'bar': 42 }; - foo = { bar: 42 }; - -and so are these: - - var b = foo['bar']; - var b = foo.bar; - -If your usage of an object is like an object, then you're defining "member -variables." For member variables, use the no-quotes no-brackets syntax: `{ bar: -42 }` `foo.bar`. - -If your usage of an object is like a hash table (and thus conceptually the keys -can have special chars in them), don't use quotes, but use brackets: `{ bar: 42 -}`, `foo['bar']`. - -Getters, setters, and Tweener ------------------------------ - -Getters and setters should be used when you are dealing with an API that is -designed around setting properties, like Tweener. If you want to animate an -arbitrary property, create a getter and setter, and use Tweener to animate the -property. - - var ANIMATION_TIME = 2000; - - var MyClass = new Lang.Class({ - Name: 'MyClass', - - _init() { - this.actor = new St.BoxLayout(); - this._position = 0; - }, - - get position() { - return this._position; - }, - - set position(value) { - this._position = value; - this.actor.set_position(value, value); - } - }); - - let myThing = new MyClass(); - Tweener.addTween(myThing, - { position: 100, - time: ANIMATION_TIME, - transition: 'easeOutQuad' }); diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 000000000..8c064999a --- /dev/null +++ b/HACKING.md @@ -0,0 +1,327 @@ +# Coding guide + +Our goal is to have all JavaScript code in GNOME follow a consistent style. In +a dynamic language like JavaScript, it is essential to be rigorous about style +(and unit tests), or you rapidly end up with a spaghetti-code mess. + +## A quick note + +Life isn't fun if you can't break the rules. If a rule seems unnecessarily +restrictive while you're coding, ignore it, and let the patch reviewer decide +what to do. + +## Indentation and whitespace + +Use four-space indents. Braces are on the same line as their associated +statements. You should only omit braces if *both* sides of the statement are +on one line. + +* One space after the `function` keyword. No space between the function name +* in a declaration or a call. One space before the parens in the `if` +* statements, or `while`, or `for` loops. +```javascript + function foo(a, b) { + let bar; + + if (a > b) + bar = do_thing(a); + else + bar = do_thing(b); + + if (var == 5) { + for (let i = 0; i < 10; i++) { + print(i); + } + } else { + print(20); + } + } +``` + +## Semicolons + +JavaScript allows omitting semicolons at the end of lines, but don't. Always +end statements with a semicolon. + +## js2-mode + +If using Emacs, do not use js2-mode. It is outdated and hasn't worked for a +while. emacs now has a built-in JavaScript mode, js-mode, based on +espresso-mode. It is the de facto emacs mode for JavaScript. + +## File naming and creation + +For JavaScript files, use lowerCamelCase-style names, with a `.js` extension. + +We only use C where gjs/gobject-introspection is not available for the task, or +where C would be cleaner. To work around limitations in +gjs/gobject-introspection itself, add a new method in `shell-util.[ch]`. + +Like many other GNOME projects, we prefix our C source filenames with the +library name followed by a dash, e.g. `shell-app-system.c`. Create a +`-private.h` header when you want to share code internally in the +library. These headers are not installed, distributed or introspected. + +## Imports + +Use UpperCamelCase when importing modules to distinguish them from ordinary +variables, e.g. +```javascript + const GLib = imports.gi.GLib; +``` +Imports should be categorized into one of two places. The top-most import block +should contain only "environment imports". These are either modules from +gobject-introspection or modules added by gjs itself. + +The second block of imports should contain only "application imports". These +are the JS code that is in the gnome-shell codebase, +e.g. `imports.ui.popupMenu`. + +Each import block should be sorted alphabetically. Don't import modules you +don't use. +```javascript + const GLib = imports.gi.GLib; + const Gio = imports.gi.Gio; + const Lang = imports.lang; + const St = imports.gi.St; + + const Main = imports.ui.main; + const Params = imports.misc.params; + const Tweener = imports.ui.tweener; + const Util = imports.misc.util; +``` +The alphabetical ordering should be done independently of the location of the +location. Never reference `imports` in actual code. + +## Constants + +We use CONSTANTS_CASE to define constants. All constants should be directly +under the imports: +```javascript + const MY_DBUS_INTERFACE = 'org.my.Interface'; +``` + +## Variable declaration + +Always use either `const` or `let` when defining a variable. +```javascript + // Iterating over an array + for (let i = 0; i < arr.length; ++i) { + let item = arr[i]; + } + + // Iterating over an object's properties + for (let prop in someobj) { + ... + } +``` + +If you use "var" then the variable is added to function scope, not block scope. +See [What's new in JavaScript 1.7](https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.7#Block_scope_with_let_%28Merge_into_let_Statement%29) + +## Classes + +There are many approaches to classes in JavaScript. We use our own class framework +(sigh), which is built in gjs. The advantage is that it supports inheriting from +GObjects, although this feature isn't used very often in the Shell itself. +```javascript + var IconLabelMenuItem = new Lang.Class({ + Name: 'IconLabelMenuItem', + Extends: PopupMenu.PopupMenuBaseItem, + + _init(icon, label) { + this.parent({ reactive: false }); + this.actor.add_child(icon); + this.actor.add_child(label); + }, + + open() { + log("menu opened!"); + } + }); +``` + +* 'Name' is required. 'Extends' is optional. If you leave it out, you will + automatically inherit from Object. + +* Leave a blank line between the "class header" (Name, Extends, and other + things) and the "class body" (methods). Leave a blank line between each + method. + +* No space before the colon, one space after. + +* No trailing comma after the last item. + +* Make sure to use a semicolon after the closing paren to the class. It's + still a giant function call, even though it may resemble a more + conventional syntax. + +## GObject Introspection + +GObject Introspection is a powerful feature that allows us to have native +bindings for almost any library built around GObject. If a library requires +you to inherit from a type to use it, you can do so: +```javascript + var MyClutterActor = new Lang.Class({ + Name: 'MyClutterActor', + Extends: Clutter.Actor, + + vfunc_get_preferred_width(actor, forHeight) { + return [100, 100]; + }, + + vfunc_get_preferred_height(actor, forWidth) { + return [100, 100]; + }, + + vfunc_paint(actor) { + let alloc = this.get_allocation_box(); + Cogl.set_source_color4ub(255, 0, 0, 255); + Cogl.rectangle(alloc.x1, alloc.y1, + alloc.x2, alloc.y2); + } + }); +``` + +## Translatable strings, `environment.js` + +We use gettext to translate the GNOME Shell into all the languages that GNOME +supports. The `gettext` function is aliased globally as `_`, you do not need to +explicitly import it. This is done through some magic in the +[environment.js](http://git.gnome.org/browse/gnome-shell/tree/js/ui/environment.js) +file. If you can't find a method that's used, it's probably either in gjs itself +or installed on the global object from the Environment. + +Use 'single quotes' for programming strings that should not be translated +and "double quotes" for strings that the user may see. This allows us to +quickly find untranslated or mistranslated strings by grepping through the +sources for double quotes without a gettext call around them. + +## `actor` and `_delegate` + +gjs allows us to set so-called "expando properties" on introspected objects, +allowing us to treat them like any other. Because the Shell was built before +you could inherit from GTypes natively in JS, we usually have a wrapper class +that has a property called `actor`. We call this wrapper class the "delegate". + +We sometimes use expando properties to set a property called `_delegate` on +the actor itself: +```javascript + var MyClass = new Lang.Class({ + Name: 'MyClass', + + _init() { + this.actor = new St.Button({ text: "This is a button" }); + this.actor._delegate = this; + + this.actor.connect('clicked', this._onClicked.bind(this)); + }, + + _onClicked(actor) { + actor.set_label("You clicked the button!"); + } + }); +``` + +The 'delegate' property is important for anything which trying to get the +delegate object from an associated actor. For instance, the drag and drop +system calls the `handleDragOver` function on the delegate of a "drop target" +when the user drags an item over it. If you do not set the `_delegate` +property, your actor will not be able to be dropped onto. + +## Functional style + +JavaScript Array objects offer a lot of common functional programming +capabilities such as forEach, map, filter and so on. You can use these when +they make sense, but please don't have a spaghetti mess of function programming +messed in a procedural style. Use your best judgment. + +## Closures + +`this` will not be captured in a closure, it is relative to how the closure is +invoked, not to the value of this where the closure is created, because "this" +is a keyword with a value passed in at function invocation time, it is not a +variable that can be captured in closures. + +All closures should be wrapped with Function.prototype.bind or use arrow +notation. +```javascript + const Lang = imports.lang; + + let closure1 = () => { this._fnorbate(); }; + let closure2 = this._fnorbate.bind(this); +``` + +A more realistic example would be connecting to a signal on a method of a +prototype: +```javascript + const Lang = imports.lang; + const FnorbLib = imports.fborbLib; + + var MyClass = new Lang.Class({ + _init() { + let fnorb = new FnorbLib.Fnorb(); + fnorb.connect('frobate', this._onFnorbFrobate.bind(this)); + }, + + _onFnorbFrobate(fnorb) { + this._updateFnorb(); + } + }); +``` + +## Object literal syntax + +In JavaScript, these are equivalent: +```javascript + foo = { 'bar': 42 }; + foo = { bar: 42 }; +``` + +and so are these: +```javascript + var b = foo['bar']; + var b = foo.bar; +``` + +If your usage of an object is like an object, then you're defining "member +variables." For member variables, use the no-quotes no-brackets syntax: `{ bar: +42 }` `foo.bar`. + +If your usage of an object is like a hash table (and thus conceptually the keys +can have special chars in them), don't use quotes, but use brackets: `{ bar: 42 +}`, `foo['bar']`. + +## Getters, setters, and Tweener + +Getters and setters should be used when you are dealing with an API that is +designed around setting properties, like Tweener. If you want to animate an +arbitrary property, create a getter and setter, and use Tweener to animate the +property. +```javascript + var ANIMATION_TIME = 2000; + + var MyClass = new Lang.Class({ + Name: 'MyClass', + + _init() { + this.actor = new St.BoxLayout(); + this._position = 0; + }, + + get position() { + return this._position; + }, + + set position(value) { + this._position = value; + this.actor.set_position(value, value); + } + }); + + let myThing = new MyClass(); + Tweener.addTween(myThing, + { position: 100, + time: ANIMATION_TIME, + transition: 'easeOutQuad' }); +``` diff --git a/README b/README deleted file mode 100644 index 0bfcf5c09..000000000 --- a/README +++ /dev/null @@ -1,20 +0,0 @@ -GNOME Shell provides core user interface functions for the GNOME 3 desktop, -like switching to windows and launching applications. GNOME Shell takes -advantage of the capabilities of modern graphics hardware and introduces -innovative user interface concepts to provide a visually attractive and -easy to use experience. - -For more information about GNOME Shell, including instructions on how -to build GNOME Shell from source and how to get involved with the project, -see: - - https://wiki.gnome.org/Projects/GnomeShell - -Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell' -product. - -License -======= -GNOME Shell is distributed under the terms of the GNU General Public License, -version 2 or later. See the COPYING file for details. - diff --git a/README.md b/README.md new file mode 100644 index 000000000..6bec164c4 --- /dev/null +++ b/README.md @@ -0,0 +1,20 @@ +# GNOME Shell +GNOME Shell provides core user interface functions for the GNOME 3 desktop, +like switching to windows and launching applications. GNOME Shell takes +advantage of the capabilities of modern graphics hardware and introduces +innovative user interface concepts to provide a visually attractive and +easy to use experience. + +For more information about GNOME Shell, including instructions on how +to build GNOME Shell from source and how to get involved with the project, +see the [project wiki][wiki] + +Bugs should be reported to the GNOME [bug tracking system][bug-tracker]. + +## License +GNOME Shell is distributed under the terms of the GNU General Public License, +version 2 or later. See the [COPYING][license] file for details. + +[project-wiki]: https://wiki.gnome.org/Projects/GnomeShell +[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues +[license]: COPYING diff --git a/browser-plugin/README b/browser-plugin/README deleted file mode 100644 index 9eccb7ca3..000000000 --- a/browser-plugin/README +++ /dev/null @@ -1,17 +0,0 @@ -The GNOME Shell Browser Plugin provides integration with gnome-shell and the -corresponding extensions repository, codenamed "SweetTooth". The plugin allows -the extensions repository to provide good integration, letting the website -know which extensions are enabled and disabled, and allowing the website to -enable, disable and install them. - -Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell' -product. - -License -======= -The GNOME Shell Browser Plugin, like GNOME Shell itself is distributed under -the GNU General Public License, version 2 or later. The plugin also contains -header files from the "NPAPI SDK" project, tri-licensed under MPL 1.1, GPL 2.0 -and LGPL 2.1. These headers are third-party sources and can be retrieved from: - - http://code.google.com/p/npapi-sdk/ diff --git a/browser-plugin/README.md b/browser-plugin/README.md new file mode 100644 index 000000000..8952e2bf3 --- /dev/null +++ b/browser-plugin/README.md @@ -0,0 +1,17 @@ +The GNOME Shell Browser Plugin provides integration with gnome-shell and the +corresponding extensions repository, codenamed "SweetTooth". The plugin allows +the extensions repository to provide good integration, letting the website +know which extensions are enabled and disabled, and allowing the website to +enable, disable and install them. + +Bugs should be reported to the GNOME [bug tracking system][bug-tracker]. + +## License +The GNOME Shell Browser Plugin, like GNOME Shell itself is distributed under +the GNU General Public License, version 2 or later. The plugin also contains +header files from the "NPAPI SDK" project, tri-licensed under MPL 1.1, GPL 2.0 +and LGPL 2.1. These headers are third-party sources and can be retrieved from: + + http://code.google.com/p/npapi-sdk/ + +[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues diff --git a/data/theme/README b/data/theme/README deleted file mode 100644 index 688892dba..000000000 --- a/data/theme/README +++ /dev/null @@ -1,31 +0,0 @@ -Summary -------- - -* Do not edit the CSS directly, edit the source SCSS files and the CSS files will be generated - automatically when building with meson + ninja and left inside the build directory to be - incorporated into the gresource XML (you'll need to have sassc installed). - -How to tweak the theme ----------------------- - -Adwaita is a complex theme, so to keep it maintainable it's written and processed in SASS, the -generated CSS is then transformed into a gresource file during gtk build and used at runtime in a -non-legible or editable form. - -It is very likely your change will happen in the _common.scss file. That's where all the widget -selectors are defined. Here's a rundown of the "supporting" stylesheets, that are unlikely to be the -right place for a drive by stylesheet fix: - -_colors.scss - global color definitions. We keep the number of defined colors to a necessary minimum, - most colors are derived from a handful of basics. It is an exact copy of the gtk+ - counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell - default. - -_drawing.scss - drawing helper mixings/functions to allow easier definition of widget drawing under - specific context. This is why Adwaita isn't 15000 LOC. - -_common.scss - actual definitions of style for each widget. This is where you are likely to add/remove - your changes. - -You can read about SASS at http://sass-lang.com/documentation/. Once you make your changes to the -_common.scss file, you can run ninja to generate the final CSS files. diff --git a/data/theme/README.md b/data/theme/README.md new file mode 100644 index 000000000..192dc65e4 --- /dev/null +++ b/data/theme/README.md @@ -0,0 +1,32 @@ +## Summary + +Do not edit the CSS directly, edit the source SCSS files and the CSS files +will be generated automatically when building with meson + ninja and left +inside the build directory to be incorporated into the gresource XML (you'll +need to have sassc installed). + +## How to tweak the theme + +Adwaita is a complex theme, so to keep it maintainable it's written and +processed in SASS, the generated CSS is then transformed into a gresource +file during gtk build and used at runtime in a non-legible or editable form. + +It is very likely your change will happen in the [_common.scss][common] file. +That's where all the widget selectors are defined. Here's a rundown of +the "supporting" stylesheets, that are unlikely to be the right place +for a drive by stylesheet fix: + +| File | Description | +| ------------------------ | ----------------- | +| [_colors.scss][colors] | global color definitions. We keep the number of defined colors to a necessary minimum, most colors are derived from a handful of basics. It is an exact copy of the gtk+ counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell default. | +| [_drawing.scss][drawing] | drawing helper mixings/functions to allow easier definition of widget drawing under specific context. This is why Adwaita isn't 15000 LOC. | +| [_common.scss][common] | actual definitions of style for each widget. This is where you are likely to add/remove your changes. | + +You can read about SASS on its [web page][sass-web]. Once you make your +changes to the [_common.scss][common] file, you can run ninja to generate the +final CSS files. + +[common]: data/theme/gnome-shell-sass/_common.scss +[colors]: data/theme/gnome-shell-sass/_colors.scss +[drawing]: data/theme/gnome-shell-sass/_drawing.scss +[sass-web]: http://sass-lang.com/documentation/ diff --git a/data/theme/gnome-shell-sass/README b/data/theme/gnome-shell-sass/README deleted file mode 100644 index 7f2a257e8..000000000 --- a/data/theme/gnome-shell-sass/README +++ /dev/null @@ -1,7 +0,0 @@ -GNOME Shell Sass is a project intended to allow the sharing of the theme sources in sass between gnome-shell and other projects like gnome-shell-extensions. - -License -======= -GNOME Shell Sass is distributed under the terms of the GNU General Public License, -version 2 or later. See the COPYING file for details. - diff --git a/data/theme/gnome-shell-sass/README.md b/data/theme/gnome-shell-sass/README.md new file mode 100644 index 000000000..7d6090ffe --- /dev/null +++ b/data/theme/gnome-shell-sass/README.md @@ -0,0 +1,10 @@ +# GNOME Shell Sass +GNOME Shell Sass is a project intended to allow the sharing of the +theme sources in sass between gnome-shell and other projects like +gnome-shell-extensions. + +## License +GNOME Shell Sass is distributed under the terms of the GNU General Public +License, version 2 or later. See the [COPYING][license] file for details. + +[license]: COPYING